home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok59.lha / AmokEd_V1.02b / txt / doc / ApplProg.dok next >
Text File  |  1993-08-15  |  7KB  |  168 lines
  1. ---------------------------------------------------------------------------
  2.  
  3.                              A m o k E d
  4.                          ===================
  5.  
  6.                              Version 1.02
  7.  
  8.                              01 Okt 1991
  9.  
  10.                              AEd_Appl.dok
  11.  
  12. ---------------------------------------------------------------------------
  13.  
  14.        Dokumentation zu AmokEd-Applikations-Programmierung
  15.        ---------------------------------------------------
  16.  
  17. Eine Applikation für AmokEd zu programmieren ist ganz leicht:
  18.  
  19. · Schreiben Sie Ihr Programm, daß es alle Funktionen beinhaltet, die
  20.   Sie haben möchten.
  21.    Wenn das Programm befehlsgesteuert ist, tun Sie sich bei der nun
  22.   folgenden Arbeit leicht.
  23.  
  24. · Ergänzen Sie Ihr Programm um eine ARexx-Schnittstelle.
  25.    Sie können nun testen, ob das Programm mit dem Rexx-Host zusammen-
  26.   arbeitet (am einfachsten über die Arexx-Funtion `trace').
  27.  
  28. · Das Programm sollte beim CLI-Aufruf als ersten Parameter den Namen
  29.   des AmokEd-Ports, mit dem es kommunizieren soll, erwarten.
  30.    Wenn das Programm einen eigenen öffentlichen Port hat, so können
  31.   sie erreichen, daß Ihr Applikation nur einmal im Speicher ist, auch
  32.   wenn sie von mehreren AmokEds genutzt wird. Wie das im Einzelnen
  33.   abläuft, ist aus dem Programm ApplDemo ersichtlich.
  34.  
  35. · Setzen Sie das Feld RexxMessage.node.node.name auf den Typ.
  36.    Sie finden die Typen in EdApplDefs.mod bereits vordefiniert. Anhand
  37.   des Typs erkennt AmokEd, daß die Nachricht von einer Applikation
  38.   kommt und welches Format sie hat.
  39.  
  40. · Die erste Nachricht die von der Applikation an AmokEd geschickt
  41.   wird, sollte die Anmeldung mit dem `APPLADD'-Befehl sein.
  42.    Überprüfen Sie den Return-Code!!
  43.    Nur wenn RexxMsg.result1 = 0, können Sie Sicher sein, daß alles
  44.   ordnungsgemäß abgelaufen ist.
  45.  
  46. · Der Befehl "CloseDown" signalisiert Ihrem Programm, das es für
  47.   AmokEd "gestorben" ist. Dieser Befehl wird beim Beenden des letzten
  48.   Textes von AmokEd an alle registrierten Applikationen geschickt;
  49.   oder auf Befehl des Anwenders an einzelne.
  50.  
  51.  
  52. Befehlsübersicht
  53. ----------------
  54.  
  55.  Von der Applikation aus können Sie alle Befehle benutzen, die Ihnen
  56. für ARexx-Scripts und innerhalb von AmokEd zur Verfügung stehen.
  57.  Zusätzlich gibt es einige Befehle, die nur für Applikationen erlaubt
  58. sind. Eine genaue Beschreibung finden sie weiter unten.
  59.  
  60. ApplAdd   - meldet eine neue Applikation bei AmokEd an (siehe oben)
  61. XPing     - setzt XPing-Feld
  62. XPong     - springt an Position n des XPing-Feldes
  63. XClrPing  - löscht das XPing-Feld
  64.  
  65.  
  66. Message-Typen
  67. -------------
  68.  
  69.  Die Parameter einer Applikation können an AmokEd auf zwei
  70. verschiedene Weisen übergeben werden. Um unterscheiden zu können,
  71. welches der beiden Formate vorliegt, muß das Feld
  72.  RexxMsg.nod.node.name den entsprechenden Typbezeichner enthalten.
  73.  Diese beiden Typen sind in EdApplDefs vordefiniert.
  74.  
  75. AEd0: RexxMsg.args[0] enthält Pointer auf einen String, der von AEd
  76.       wie ein gewöhnlicher Kommando-String von ARexx behandelt wird.
  77.       D.h. er wird ganz normal durch den Parser geschickt.
  78.        Wenn der übergebene String nicht nur aus alphanumerischen
  79.       Zeichen und Underscores '_' besteht, sollten Sie nicht den
  80.       String selbst übergeben, sondern einen ARexx-Argstring. (Siehe
  81.       hierzu auch Programm ApplDemo.)
  82.  
  83. AEd1: Dieser Typ erleichter die Kommunikation zwischen der Applikation
  84.       und AmokEd erheblich, da nicht extra ein String zusammengesetzt
  85.       werden muß, den AmokEd dann wieder parset. Die Argumente werden
  86.       gleich einzeln übergeben. Das macht nicht nur die Applikationen
  87.       kürzer, sondern beschleunigt auch die Abarbeitung.
  88.        Mit diesem Typ können alle Befehle benutzt werden, die AmokEd
  89.       versteht. Sie müssen nur beachten, daß die Argumente der
  90.       normalen und der Rexx-Befehle IMMER als StringPtr interpretiert
  91.       werden.
  92.  
  93.        RexxMsg.arg[0] enthält einen StringPtr. Der referenzierte
  94.       String, der wird darf jedoch nur und genau ein gültiges Kommando
  95.       enthalten (ohne Argumente), da dieser String als unverändertes
  96.       Ganzes zum Vergleich mit der Liste der gülitgen Kommandos
  97.       benutzt wird
  98.        Die folgenden RexxMsg.args[]-Felder enthalten die Argumente des
  99.       auszuführende Befehls. Bei den normalen und den Rexx-Befehlen
  100.       sind das immer StringPtr.
  101.        Sie können im Anschluß daran noch weitere Befehle mit
  102.       Argumenten übergeben, sofern alle Argumente in die noch zur
  103.       Verfügung stehenden RexxMsg.args[]-Felder passen. Bedenken Sie
  104.       jedoch, daß in args[eAD.TextSlot] der Bezugs-Text eingetragen
  105.       wird. Es stehen daher eAD.numAMArgs args[]-Felder zur Verfügung.
  106.  
  107.       WICHTIG:
  108.        Das erste, nicht mehr benutzte args[]-Feld MUSS auf NIL gesetzt
  109.       werden! Dies trifft natürlich nicht zu, wenn Sie alle
  110.       eAD.numAMArgs Felder benutzen.
  111.  
  112.       Ein kleines Beispiel:
  113.        Wir haben 3 Befehle (Anzahl der Agumente in Klammern):
  114.       foo (2), bar (0) und foobar (1).
  115.        Dann könnten wir folgende RexxMsg schicken:
  116.          args[0] := ADR("foo");
  117.          args[1] := fooarg1;
  118.          args[2] := fooarg2;
  119.          args[3] := ADR("bar");
  120.          args[4] := ADR("foobar");
  121.          args[5] := foobar_arg;
  122.          args[6] := NIL;
  123.          args[eAD.TextSlot] := Text; (* Text wurde übergeben *)
  124.  
  125.  
  126. Die Applikations-Befehle
  127. ------------------------
  128.  
  129. ADDAPPL <name> <port> Meldet eine Applikation bei AmokEd an. Sie ist
  130.                       anschließend für den Benutzen unter <name>
  131.                       anprechbar. <port> ist der Name des öffentlichen
  132.                       Ports, unter dem die Applikation erreichbar ist.
  133.  
  134.                       <name> StringPtr
  135.                       <port> StringPtr
  136.  
  137. XPING <adr>           Teilt AmokEd mit, an welcher Adresse sich die
  138.                       Struktur eAD.XPingPong befindet, die die Marken
  139.                       für XPong enthält.
  140.                       Zur Zeit kann AmokEd je Text nur ein XPingPong-
  141.                       Feld verwalten.
  142.                       Aus Gründen der Aufwärtskompatibilität sollte
  143.                       der Speicher dieser Struktur PUBLIC sein.
  144.  
  145.                       <adr> eAD.XPingPongPtr
  146.  
  147. XPong <num>           Veranlaßt AmokEd, an die Position und in die
  148.                       Zeile zu springen, die an <num> in die Struktur
  149.                       XPingPong eingetragen ist.
  150.                        Sollte diese Position nicht mehr gültig sein,
  151.                       erhalten die einen entsprechenden Fehler-Code.
  152.  
  153.                       <num> LONGINT
  154.  
  155. ClrXPing              Veranlaßt AmokEd, den Verweis auf die Struktur
  156.                       XPingPong des Textes zu entfernen.
  157.                       Jetzt kann der Inhalt der Struktur geändert oder
  158.                       der zugehörige Speicher freigegeben werden.
  159.  
  160.                       "Besitzt" Ihre Applikation eine Message von dem
  161.                       AmokEd (es können ja mehrere gleichzeitg
  162.                       laufen), zu dem der Text gehört, so kann die
  163.                       Applikation sie Struktur auch ändern, ohne
  164.                       vorher ClrXPing aufzurufen. Sobald die Message
  165.                       repleied wurde, darf die Struktur nicht mehr
  166.                       verändert werden!
  167.  
  168.